Apple WWDC 1996

home *** CD-ROM | disk | FTP | other *** search

/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UView.h < prev next >

Wrap

Text File | 1996-04-03 | 54.7 KB | 1,468 lines | [TEXT/MPS ]

// UView.h // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved. #ifndef __UVIEW__ #define __UVIEW__ // MacApp #ifndef __UADORNERS__ #include "UAdorners.h" #endif #ifndef __UCOMMANDHANDLER__ #include "UCommandHandler.h" #endif #ifndef __UGEOMETRY__ #include "UGeometry.h" #endif #ifndef __UITERATOR__ #include "UIterator.h" #endif // Toolbox #ifndef __BALLOONS__ #include <Balloons.h> #endif #if qDrag # ifndef __DRAG__ # include <Drag.h> # endif #endif #if qGXViews || qGXPrinting # ifndef __GXTYPES__ # include <GXTypes.h> # endif #endif //---------------------------------------------------------------------------------------- // Forward and external class declarations. //---------------------------------------------------------------------------------------- class CAEDesc; class CDragItemIterator; class TAdorner; class TAdornerList; class TDesignator; class TDocument; class TDragItem; class TDrawingEnvironment; class TPrintHandler; class TScroller; class TToolboxEvent; class TWindow; //---------------------------------------------------------------------------------------- // MouseDownType //---------------------------------------------------------------------------------------- enum EMouseDownType { //kDragOnly, // (never used) kDragOrClick, // !isFirstClick kFirstClick_dragOnly, // isFirstClick !windowDoesFirstClick kFirstClick_dragOrClick // isFirstClick windowDoesFirstClick }; //---------------------------------------------------------------------------------------- // Constants //---------------------------------------------------------------------------------------- const unsigned char kFrame = adnLineTop | adnLineLeft | adnLineBottom | adnLineRight; // Defines that a view be completely framed. const Boolean kImmediateSuperView = TRUE; // Used with GetScroller to return only the // scroller of the immediate superview const Boolean kAnySuperView = FALSE; // Used with GetScroller to return scroller // in the super view chain const Boolean kInsertSubViewFirst = FALSE; // Use to insert subviews at the front of // the list rather than the end (default). //---------------------------------------------------------------------------------------- // SizeDeterminer: Tells how a view's size is to be determined; specified separately in // each dimension. //---------------------------------------------------------------------------------------- enum SizeDeterminer { sizeSuperView, // View is the same size as its superview sizeRelSuperView, // View size is relative to the // superview's size sizePage, // View to be the size of one page sizeFillPages, // View to grow upward to fill an exact // number of pages sizeVariable, // View size fluctuates according to // app-specific criteria sizeFixed }; //---------------------------------------------------------------------------------------- // ViewPortInfo: Set by GetFocus; used by SetFocus. GetFocus/ SetFocus are used to save and // restore the focus behind MacApp's back. //---------------------------------------------------------------------------------------- struct ViewPortInfo { CPoint org; GrafPtr port; RgnHandle clip; Boolean isValid; // true if FocusRec is valid }; //---------------------------------------------------------------------------------------- // FocusRec //---------------------------------------------------------------------------------------- struct FocusRec { ViewPortInfo itsViewPortInfo; Boolean printing; Boolean drawingPictScrap; TView* drawingPictScrapView; TView* focusedView; }; //---------------------------------------------------------------------------------------- // TView: Renders an image of a document or other data, and identifies mouse-clicked // objects. //---------------------------------------------------------------------------------------- class TView : public TCommandHandler { MA_DECLARE_CLASS; public: //------------------------------------------------------------------------------------ // Creation/ Destruction Methods //------------------------------------------------------------------------------------ TView(); // Constructor void IView(TDocument* itsDocument, TView* itsSuperView, const VPoint& itsLocation, const VPoint& itsSize, SizeDeterminer itsHSizeDet, SizeDeterminer itsVSizeDet); // Initializes a view procedurally. void HandlePostCreate(TDocument* itsDocument); // Post-order traversal calling DoPostCreate virtual void DoPostCreate(TDocument* itsDocument); // Called in a post-order traversal of a newly-created view hierarchy virtual TObject* Clone(); // Calls Inherited::Clone and then clones owned objects. virtual ~TView(); // Frees its subviews, then if its superview is not NULL removes itself from the // superviews list of subviews and if its document is not NULL removes itself from // the documents list of views. If it has a print handler then it frees it, then // calls Inherited::Free. Frees its fAdorners list. virtual void FreeFromClipboard(); // If its document is not NULL then calls the document's FreeFromClipboard method, // otherwise calls Free. //------------------------------------------------------------------------------------ // Standard signature support. //------------------------------------------------------------------------------------ virtual IDType GetStandardSignature(); // override // Returns this class's standard signature. //------------------------------------------------------------------------------------ // Stream I/O protocol support. //------------------------------------------------------------------------------------ virtual void ReadFrom(TStream* aStream); virtual void ReadFields(TStream* aStream); virtual void ReadSubViews(TStream* aStream); virtual void WriteTo(TStream* aStream); virtual void WriteFields(TStream* aStream); virtual void WriteSubViews(TStream* aStream); //------------------------------------------------------------------------------------ // Coordinate Conversion Methods //------------------------------------------------------------------------------------ VPoint QDToViewPt(CPoint qdPoint); inline void QDToViewPt(CPoint qdPoint, VPoint& viewPt) { viewPt = QDToViewPt(qdPoint); } // Convert a QuickDraw point to a view point. VRect QDToViewRect(const CRect& qdRect); inline void QDToViewRect(const CRect& qdRect, VRect& viewRect) { viewRect = QDToViewRect(qdRect); } // Convert a QuickDraw CRect to a view rect. CPoint ViewToQDPt(const VPoint& viewPt); // Convert a view point to a QuickDraw point. CRect ViewToQDRect(const VRect& viewRect); inline void ViewToQDRect(const VRect& viewRect, CRect& qdRect) { qdRect = ViewToQDRect(viewRect); } // Convert a view rect to a QuickDraw CRect. VPoint GetLocalOffsetInSuper() const; inline void GetLocalOffsetInSuper(VPoint& localOffsetInSuper) const { localOffsetInSuper = GetLocalOffsetInSuper(); } // Returns the location of the origin for this view coordinate systemin the // superview's coordinate system virtual void SetLocalOrigin(const VPoint& newOrigin, Boolean redraw); // Sets the origin of the view's local coordinate system. Redraws if requested. void LocalToSuper(VPoint& thePoint) const; // Given a point in local view coordinates, returns the same point in its // superview's coordinate system. void LocalToSuperVRect(VRect& viewRect) const; // Given a rect in local view coordinates, returns the same rect in its // superview's coordinate system. void LocalToSuperRegion(RgnHandle theRgn); // Given a region in local view coordinates, returns the same region in its // superview's coordinate system. void LocalToGlobalRegion(RgnHandle theRgn); // Given a region in local view coordinates, returns the same region in // global screen coordinates. void LocalToWindowRegion(RgnHandle theRgn); // Given a region in local view coordinates, returns the same region in its // window's coordinate system. void LocalToWindow(VPoint& thePoint) const; // Given a point in local view coordinates, returns the same point in its window's // (or most super superview's) coordinate system. void SuperToLocal(VPoint& thePoint) const; // Given a point in superview coordinates, returns the same point in the view's // own coordinate system. void SuperToLocalVRect(VRect& viewRect) const; // Given a rect in superview coordinates, returns the same rect in the view's own // coordinate system. void SuperToLocalRegion(RgnHandle theRgn); // Given a region in superview coordinates, returns the same region inthe view's // own coordinate system. void WindowToLocal(VPoint& thePoint) const; // Given a point in window (or most super superview) coordinates, returns the same // point in the view's own coordinate system. //------------------------------------------------------------------------------------ // SubView Management Methods //------------------------------------------------------------------------------------ void InsertSubView(TView* theSubView, Boolean last = TRUE); // Add 'theSubView' to our list of subviews. By default adds to end of list // (in drawing order). To add to the front of the list, pass kInsertSubViewFirst. // Just does list manipulation doesn't do any sub/superview notification void DeleteSubView(TView* theSubView); // Remove 'theSubView' from our list of subviews. // Just does list manipulation doesn't do any sub/superview notification void AddSubView(TView* theSubView); // Add 'theSubView' to our list of subviews. void RemoveSubView(TView* theSubView); // Remove 'theSubView' from our list of subviews. void MakeFirstSubView(TView* theSubView); // Make 'theSubView ' the first subview in our list. void MakeLastSubView(TView* theSubView); // Make 'theSubView' the last subview in our list. short CountSubViews() const; // Return the number of subviews in our view. inline Boolean HasSubViews() const { return (fSubView != NULL); } // True if this view has subviews. inline TView* FirstSubView() const { return fSubView; } // Return the first subview in our list (NULL if none). TView* FindSubView(IDType itsIdentifier) const; // Find subview with identifier 'itsIdentifier' in our list of subviews. Boolean ContainsSubView(TView* aView) const; // Returns true if aView is in the view hierarchy with this view as root //------------------------------------------------------------------------------------ // Open/ Close/Activate Methods //------------------------------------------------------------------------------------ virtual void Activate(Boolean entering); // Focuses and then highlights any current selection before calling all its // subviews to activate themselves. virtual void Open(); // Calls each of its subviews to Open themselves. virtual void Close(); // Commits the last command before calling each of its subviews to Close // themselves. virtual void BeInDocument(TDocument* itsDocument); // If 'itsDocument' is not NULL then sets its fDocument to itsDocument and // add itself to the documents viewlist. virtual void BeInScroller(TScroller* itsScroller); // If 'itsScroller' is not NULL then sets its scroll limits to its fSize. virtual void BeInPort(GrafPtr itsPort); // If its print handler is not NULL, calls DoCheckPrinter. Then calls each of its // subviews to BeInPort. virtual void ShowReverted(); // First calls AdjustSize before forcing a redraw of the view, then call // ShowReverted for each of its subviews. //------------------------------------------------------------------------------------ // Frame (Location and Size) Methods //------------------------------------------------------------------------------------ virtual void SetFrame(const VRect& newFrame, Boolean invalidate); // sets our frame to newFrame, invalidating if 'invalidate' is true. virtual void InvalidateFrameDifference(const VRect& oldFrame, const VRect& newFrame); // Invalidates the difference between the old and new frames, unless the location has // changed, in which case the union of the two frames is invalidated. virtual void NotifyAdornersOfFrameChange(const VRect& oldFrame, const VRect& newFrame, Boolean invalidate); // Iterates over this view's adorners, calling ViewChangedFrame. Called by TView::SetFrame virtual void NotifySubViewsOfFrameChange(const VRect& oldFrame, const VRect& newFrame, Boolean invalidate); // Iterates over this view's subviews, calling SuperViewChangedFrame. Called by TView::SetFrame virtual void Locate(const VPoint& newLoc, Boolean invalidate); // Convenience routine. Sets the frame to newLoc. Don't override it since // MacApp usually calls SetFrame instead. virtual void Resize(const VPoint& newSize, Boolean invalidate); // Convenience routine. Sizes the frame to newSize. Don't override it since // MacApp usually calls SetFrame instead. virtual void AdjustFrame(); // Calls ComputeFrame, if the size has changed resizes itself and then calls // DoPagination so that any page breaks can be recalculated. virtual VRect CalcMinFrame(); // Calculate the minimum size of this. virtual void ComputeFrame(VRect& newFrame); // Called by MacAppto get the size of the view computed. virtual void SuperViewChangedFrame(const VRect& oldFrame, const VRect& newFrame, Boolean invalidate); // Called when our superview changes frame. virtual void SubViewChangedFrame(TView* theSubView, const VRect& oldFrame, const VRect& newFrame, Boolean invalidate); // Called when one of our subviews changes frame. //------------------------------------------------------------------------------------ // Focusing Methods //------------------------------------------------------------------------------------ virtual Boolean Focus(); // Attempts to set up the drawing environment for this view. That consists of // port, origin, gLongOffset and clipping. Returns false if not able to focus. One // reason focus could fail is if no superview is able to supply a port (ie not in // a window and not printing or drawing pict scrap). Focus will return true, // however, if the drawing environment can be setup but none of the view is // currently visible due to clipping or scrolling by a superview. This lets you // assemble view hierarchies and manipulate views without showing them to the // user, but requires that you test IsVisible if you MUST know if the view is in // fact visible. (MacApp will never ask a view to draw unless it is visible) virtual Boolean FocusOnSuperView(); // Focuses on our superview. inline void InvalidateFocus() { gFocusedView = NULL; } // Indicates that the view's focus is no longer valid and must be recomputed. inline Boolean IsFocused() const { return gFocusedView == this; } // Check to see if we are currently focused. void ClipFurtherTo(RgnHandle rRgn, CPoint deltaOrg); // Set clipping to: (<current clipping> INTERSECT r) OFFSET-BY deltaOrg. void OffsetAndClipFurtherTo(RgnHandle rRgn, CPoint deltaOrg); // Set clipping to: OFFSET-BY deltaOrg and (<current clipping> // INTERSECT r). #if qDebug void AssumeFocused() const; // Causes a ProgramBreak if the focused view isn't this. #endif void InvalidateCoordinates(); // Indicates that the view's computed offsets are no longer valid and must be // recomputed. Calls InvalidateCoordinates for all subviews. virtual void UpdateCoordinates(); // Called If a coordinate related field must be retrieved and the coordinates // are invalid. VRect GetVisibleExtent(); // Retrieves the fVisibleExtent, calls UpdateCoordinates if necessary. CPoint GetQDOrigin(); // Retrieves the fQDOrigin, calls UpdateCoordinates if necessary. VPoint GetViewToQDOffset(); // Retrieves the fViewToQDOffset, calls UpdateCoordinates if necessary. //------------------------------------------------------------------------------------ // Adornment Methods //------------------------------------------------------------------------------------ virtual TAdornerList* MakeAdornerList(); void AddAdorner(TAdorner* anAdorner, AdornPriority itsPriority, Boolean invalidate); // adds an adorner to the view; invalidates the adorner if "invalidate" is true void DeleteAdorner(TAdorner* anAdorner, Boolean invalidate); // removes an adorner from the view; invalidates the adorner if "invalidate" is // true void DeleteAdornerByID(IDType itsID, Boolean invalidate); // removes an adorner from the view; invalidates the adorner if "invalidate" is // true TAdorner* AdornerAt(ArrayIndex i) const; // Returns the i'th adorner in the list TAdorner* AdornerWithID(IDType itsID) const; // Returns the first adorner with the specified ID virtual void Dim(); // dims the current image in the view virtual void GetAdornExtent(VRect& itsAdornExtent); // returns the adorn extent for adorning this view virtual void Hilite(); // hilites the current image in the view by inverting its extent //------------------------------------------------------------------------------------ // Drawing Methods //------------------------------------------------------------------------------------ virtual TDrawingEnvironment* DoMakeNewDrawingEnvironment(); // Create a new drawing environment void CreateDrawingEnvironment(); // Creates a new drawing environment, if none exists. void SetDrawingEnvironment(TDrawingEnvironment* itsDrawingEnvironment, Boolean invalidate); // Frees the old drawing environment and stores the new one. inline TDrawingEnvironment* GetDrawingEnvironment() const { return fDrawingEnvironment; } // Returns this view's drawing environment object, which may be NULL. void PrepareForDrawing(); // A possible "hook" for doing offscreen drawing. // If the view has an fDrawingEnvironment, calls its Prepare method. // Calls SetupDrawingEnvironment. void SetupDrawingEnvironment(); // If the view has an fDrawingEnvironment, calls its Setup method. // Otherwise calls PenNormal. void CompleteDrawing(); // If the view has an fDrawingEnvironment, calls its Complete method. // A possible "hook" for doing offscreen drawing virtual void UpdateSelection(const VPoint& /* theMouse */, TToolboxEvent * /* event */); // Called prior to DoMouseDown and WillDrag. Provides an opportunity // to update selection before being asked to drag or handle a mouse // down. virtual void DoHighlightSelection(HLState fromHL, HLState toHL); // Currently does nothing. Must be overridden. HLState GetCurrentHL(); // Returns fActiveHL if the view is active, otherwise fInActiveHL. virtual void Draw(const VRect& area); // Currently does nothing. Must be overridden. void HandleDraw(const VRect& area); // Causes the area of the views contents to be drawn and that of any of its subviews. void DrawContents(); // Causes the views contents to be drawn and that of any of its subviews. void DrawAdorners(const VRect& area); // Asks each adorner in the list of adorners to draw void HighlightAdorners(const VRect& area, HLState fromHL, HLState toHL); // Calls each adorner's DoHighlightSelection method virtual TDesignator* GetUserSelection(); // Returns the designator for the user selection (if any).Defaults to returning // the user selection of the document (if any) virtual void SetUserSelection(TDesignator* newSelection); // Sets the designator for the user selection (if any). Defaults to setting the // user selection of the document (if any) virtual void UserSelectionChanged(TView* changedView); // Call this whenever the user's selection changes. Defaults to calling the // UserSelectionChanged method of the document (if any). virtual void ScrollSelectionIntoView(Boolean redraw); // Scroll the selection into view. virtual Boolean HasPendingUpdate(); // Returns true if there is a pending update event for this view, false if not. virtual void Update(); // If its window is not NULL then does an update by calling DrawContents. //------------------------------------------------------------------------------------ // Validation/ Invalidation Methods //------------------------------------------------------------------------------------ virtual void ForceRedraw(); // Invalidates the entire view forcing a redraw. void InvalidateVRect(const VRect& badVRect); // Invalidates a QuickDraw CRect by calling InvalidateRect. void InvalidateRect(const CRect& badRect); // Invalidates a View CRect by calling InvalidateRegion. void InvalidateRegion(const RgnHandle badRgn); // Intersects badRgn with the visible extent then calls DoInvalidateRegion with the // result. We can only call InvalidRgn on a grafPort belonging to a window, if // your code calls InvalidRgn on a non-window grafPort, it will die miserably. So // views forward up their superview chain until they reach a view which overrides // DoInvalidateRegion (usually a window) which then makes the actual InvalidRgn call virtual void DoInvalidateRegion(const RgnHandle badRgn); // Invalidates a Region by passing it to the superview void ValidateVRect(const VRect& goodVRect); // Validates a view rect by calling ValidateRect. void ValidateRect(const CRect& goodRect); // Validates a QuickDraw rect by calling ValidateRegion. void ValidateRegion(const RgnHandle goodRgn); // Intersects goodRgn with the visible extent then calls DoValidateRegion with the // result. We can only call ValidRgn on a grafPort belonging to a window, if your // code calls ValidRgn on a non-window grafPort, it will die miserably. So views // forward up their superview chain until they reach a view which overrides // DoValidateRegion (usually a window) which then makes the actual ValidRgn call virtual void DoValidateRegion(const RgnHandle goodRgn); // Validates a Region by passing it to the superview virtual void RevealRect(const VRect& rectToReveal, const VPoint& minToSee, Boolean redraw); // Scrolls a rect into view, with 'minToSee' being the point which will end up at // the bottom of the view, i.e.the minimum amount to be seen and 'rectToReveal' // the rect being scrolled. void RevealTop(Boolean redraw); // Scroll the top of a rect into view. void RevealBottom(Boolean redraw); // Scroll the bottom of a rect into view. virtual void RevealUndoRedo(TCommand* command); // override // Make this context visible after undo/redo. //------------------------------------------------------------------------------------ // Mouse Handling Methods //------------------------------------------------------------------------------------ virtual EventNumber GetEventNumber(); // Returns cNoEvent. Overridden by TControl. virtual Boolean ContainsMouse(const VPoint& theMouse); // Is the view point 'theMouse' currently in our view. virtual Boolean HandleMouseDown(const VPoint& theMouse, TToolboxEvent* event, CPoint hysteresis, EMouseDownType mouseDownType = kDragOrClick); // The method responsible for handling a mouse down in the view, calls // DoMouseUp to handle it. virtual Boolean HandleMouseUp(const VPoint& theMouse, TToolboxEvent* event, CPoint hysteresis); // The method responsible for handling a mouse up in the view, calls // DoMouseUp to handle it. virtual void DoMouseCommand(VPoint& theMouse, TToolboxEvent* event, CPoint hysteresis); // Posts a simple tracker which by default calls back tracking methods of this // view. There are two possibilities here: 1) Override DoMouseCommand to post // commands that represent more complex, even undoable actions.That command may // either let its tracking call back the view's tracking methods (the default) // which must be overridden to do anything useful or it may simply do all the // tracking itself. This mostly depends on whether different commands returned // from the view would have different tracking behavior.For example this is the // approach taken by DrawShapes. 2) Override the view's tracking methods and let // the default tracker them.For example this is the approach taken by TControl. virtual void DoMouseUp(VPoint& theMouse, TToolboxEvent* event, CPoint hysteresis); // Called for the most deeply nested view that contains the mouse. //------------------------------------------------------------------------------------ // Cursor and Help Handling Methods //------------------------------------------------------------------------------------ void RestrictRegionToVisible(RgnHandle aRegion); // Restricts the region to the visible extent of this view virtual Boolean HandlesCursor(); // Returns true, if this view tracks the mouse so that it can claim the cursor. // The default returns true. If false, subviews may still get a chance to set the // cursor, as determined by TView::SubViewsHandleCursor. virtual Boolean LetsSubViewsHandleCursor(); // Returns true if this view should allow subviews a chance to set the cursor. If // true, the subviews themselves may still return false for HandlesCursor. By // setting both values false, cursor tracking can be turned off for an entire // window, such as the clipboard window. virtual Boolean HandlesHelp(); // Returns true, if this view tracks the mouse so that it can show help. The // default returns true. If false, subviews may still get a chance to show help, // as determined by TView::SubViewsHandleHelp. virtual Boolean LetsSubViewsHandleHelp(); // Returns true if this view should allow subviews a chance to show help. The // subviews themselves may still return false for HandlesHelp. By setting both // values false, help can be turned off for an entire view hierarchy void HandleCursor(const VPoint& theMouse, RgnHandle cursorRegion); // Try to find a subview that contains the mouse and wants to handle the cursor. // Otherwise, call our behaviors' DoSetCursor method and then our own DoSetCursor // method to actually set the cursor. void HandleHelp(const VPoint& theMouse, RgnHandle helpRegion); // Try to find a subview that contains the mouse and wants to handle the help. // Otherwise, call our own DoShowHelp method to actually show the help balloon. virtual void DoSetCursor(const VPoint& localPoint, RgnHandle cursorRegion); // Can be overridden to set the cursor and compute a cursor region. The default // sets the cursor to an arrow and uses TView::GetDefaultCursorRegion to compute the // largest appropriate cursor region virtual ResNumber GetHelpID(); // Returns fHelpID. virtual short GetHelpIndex(); // Returns fHelpIndex. virtual short GetHelpState(); // Returns kHMEnabledItem, kHMDisabledItem, etc. virtual ResNumber GetCursorID(); // Returns fCursorID. void GetHelpParameters(const VPoint& localPoint, RgnHandle helpRegion, HMMessageRecord& helpMessage, CPoint& localQDTip, CRect& localQDRect, short& balloonVariant); // Determine the parameters needed for showing a help balloon for this view. The // default calls the TApplication method of the same name which gets the information // from a resource of type 'hdlg'. The fields fHelpID and fHelpIndex specify the // resource and component within the resource containing the information for this // view. void DoShowBalloon(const VPoint& localPoint, RgnHandle helpRegion, const HMMessageRecord& helpMessage, CPoint localQDTip, const CRect& localQDRect, short balloonVariant); // Show the help balloon. void DoShowHelp(const VPoint& localPoint, RgnHandle helpRegion); // Gets the help parameters and shows the help balloon. virtual void GetDefaultCursorRegion(const VPoint& localPoint, RgnHandle cursorRegion); // Returns the largest appropriate cursor region, called by DoSetCursor. virtual void GetDefaultHelpRegion(const VPoint& localPoint, RgnHandle helpRegion); // Returns the largest appropriate help region, called by DoShowHelp. //------------------------------------------------------------------------------------ // Miscellaneous Methods //------------------------------------------------------------------------------------ virtual TCommandHandler* GetContext(CommandNumber aCommandNumber); // Override // Returns the view's document, if any, or the view itself. virtual GrafPtr GetGrafPort(); // Returns a pointer to our Graf Port. virtual TScroller* GetScroller(Boolean immediateSuperView); // Returns a reference to our scroller. virtual TView* GetRootView(); // Returns a reference to the root view. virtual TWindow* GetWindow() const; // Returns a reference to the window that we are in, if any. VRect GetExtent() const; inline void GetExtent(VRect& itsExtent) const { itsExtent = GetExtent(); } // Returns a view CRect the size of our extent in 'itsExtent'. virtual void GetExtentRegion(RgnHandle itsExtentRgn); // Shapes the supplied region to the view's extent. Override for non-rectangular // views to return a region for the drawable (qdExtent) portion of the view. CRect GetQDExtent(); inline void GetQDExtent(CRect& qdExtent) { qdExtent = GetQDExtent(); } // Returns a QuickDraw CRect the size of our extent in 'qdExtent'. VRect GetFrame() const; inline void GetFrame(VRect& itsFrame) const { itsFrame = GetFrame(); } // Returns in'itsFrame' a VRect that is the boundary of our view in superview // coordinates. This is calculated by adding its size to its location. VRect GetVisibleRect(); inline void GetVisibleRect(VRect& visRect) { visRect = GetVisibleRect(); } // Returns a CRect enclosing the visible portion of the view in view coordinates. CRect GetVisibleQDRect(); inline void GetVisibleQDRect(CRect& visQDRect) { visQDRect = GetVisibleQDRect(); } // Returns a CRect enclosing the visible portion of the view in QD coordinates. void GetVisibleRegion(RgnHandle visibleRgn); // Returns a visibleRgn enclosing the drawable portion of the view in QD coordinates. VRect GetDrawableRect(); inline void GetDrawableRect(VRect& drawRect) { drawRect = GetDrawableRect(); } // Returns a CRect enclosing the drawable portion of the view in view coordinates. CRect GetDrawableQDRect(); inline void GetDrawableQDRect(CRect& drawQDRect) { drawQDRect = GetDrawableQDRect(); } // Returns a CRect enclosing the drawable portion of the view in QD coordinates. void GetDrawableRegion(RgnHandle drawRgn); // Returns a drawRgn enclosing the drawable portion of the view in view coordinates. virtual short GetPartCode(const VPoint& theMouse); // tells which part of a view, if any, the mouse button was pressed in. Returns: // inContent = 3, inDrag = 4, inGrow = 5, inGoAway = 6, or inDesk = 0 (ie. none of // the above),depending on where theMouse is in the view void ViewEnable(Boolean state, Boolean redraw); // Enables & Redraws the view based on 'state' & 'redraw'. virtual void Show(Boolean state, Boolean redraw); // If 'state' is not fShown then set fShown to true and call ForceRedraw if // 'redraw' is true. Otherwise invalidate our focus and set fShown to 'state'. virtual Boolean IsShown(); // Checks to see if our view is currently shown. Boolean IsVisible(); // Returns true if any portion of the view is currently visible when focused Boolean IsDrawable(); // Returns true if any portion of the view is currently drawable when focused virtual Boolean IsActive(); // Returns true if the view is in an "active" superview (typically a window) //------------------------------------------------------------------------------------ // Target Management and Validation //------------------------------------------------------------------------------------ virtual Boolean WantsToBeTarget(); // Override // Returns the value of fWantsToBeTarget virtual long GetValidationError(); // Returns an error value "noErr". Overridden by TEditText and TNumberText. // Formerly known as "Validate" Boolean IsValid(); // Returns true if this view is in a valid state. Calls ValidationFailed // if it is not. Boolean IsHierarchyValid(); // Returns true if this view and all its subviews are in a valid state. // User may be alerted via ValidationFailed method. virtual void ValidationFailed(long reason); // Can be overridden to alert the user, as is done by TEditText. TView* FindTarget(); // Find a subview which wants to be the target virtual void SetTargetSelection(Boolean redraw); // Override // Called when this object becomes the target, except as a result of a mouse click // Overridden to reveal the view if it is scrolled out of view //------------------------------------------------------------------------------------ // Clipboard Handling //------------------------------------------------------------------------------------ virtual PicHandle AsPict(); // Returns a PicHandle containing a rendering of the view and its subviews. virtual Boolean ContainsClipType(ResType aType); // Checks to see if the clipboard contains the type 'aType'. virtual long GivePasteData(Handle aDataHandle, ResType dataType); // Gets the scrap data of the type 'dataType', returns any errors as function // result. virtual void WriteToDeskScrap(); // Writes to desk scrap. //------------------------------------------------------------------------------------ // PrintingMethods //------------------------------------------------------------------------------------ TPrintHandler* GetPrintHandler(); // return the associated print handler, if any. void AttachPrintHandler(TPrintHandler* itsPrintHandler); // Called by the PrintHandler during its initialization, NOT directly by you void DetachPrintHandler(TPrintHandler* itsPrintHandler); // Called by the PrintHandler when freed, NOT directly by you virtual VCoordinate DoBreakFollowing(VHSelect vhs, VCoordinate previousBreak, Boolean& automatic); // Returns the location of the page break which follows the page break located at // 'previousBreak', in direction vhs; returns automatic = true if the page-break is // thought of as an 'automatic' rather than a 'manual' (user-specified) one. Note // that page-breaks in dimension 'v' are drawn as vertical lines, those in // dimension 'h' as horizontal lines virtual VPoint DoCalcPageStrips(); // Computes the number of horizontal and vertical page strips. virtual VPoint DoCalcViewPerPage(); // Determine how much of the view normally goes into each printed page, in each // dimension. virtual void DoCheckPrinter(); // Check whether printer (if relevant) has changed, and if so, take appropriate // action virtual void DoDrawPrintFeedback(const VRect& area); // Draw page-breaks, page-numbers, view-borders, rulers, etc. virtual void DoDrawPageBreak(VHSelect vhs, short whichBreak, VCoordinate loc, Boolean automatic); // Draw one page break. virtual void DoPagination(); // Recompute the dividing lines between areas of the view which will be mapped // into different printed pages virtual void DoPrinterChanged(); // The metrics relating to printer use have changed; absorb the information and // react virtual void DoSetPageOffset(const VPoint& coord); // Only reimplement in very unusual circumstances involving Tall-UnAdjusted text // printing etc. virtual VRect GetPrintExtent(); // Returns the part of the view that is to be printed. The default is to return // the view's extent. virtual void PageInteriorChanged(const VRect& newInterior); // Allows a view which is printable to react to the changing of the page-interior // rectangle //------------------------------------------------------------------------------------ // View Tracking Methods //------------------------------------------------------------------------------------ virtual void GoAwayByUser(const VPoint& theMouse); // Provides tracking for the GoAway box (or other indicator) and calls CloseByUser // if go away was indicated. virtual void MoveByUser(const VPoint& theMouse); // Provides tracking for the Title bar (or other drag area) and calls Locate if // the location changed. virtual void ResizeByUser(const VPoint& theMouse); // Provides tracking for the Resize box (or other indicator) and calls Resize if // the size changed. virtual void ZoomByUser(const VPoint& theMouse, short partCode); // Provides tracking for the Zoom box (or other indicator) and calls Zoom if zoom // was indicated. //------------------------------------------------------------------------------------ // Tracker Tracking Methods //------------------------------------------------------------------------------------ virtual Boolean IsDoneTracking(); // Indicates whether the Tracker is through tracking.(the command is also through // tracking if you return NULL from TrackMouse). Defaults to NOT StillDown. Most // programs won't have to mess with this. NOTE you still have to deal with queued // events if you change the criteria for true. virtual void TrackConstrain(TrackPhase aTrackPhase, const VPoint& anchorPoint, const VPoint& previousPoint, VPoint& nextPoint, Boolean mouseDidMove); // Override this if your Tracker calls back to the view (the Default) and you want // to constrain the mouse point to a grid, force drawing a square, etc. This is // called only if fConstrainsMouse is true. virtual void TrackFeedback(TrackPhase aTrackPhase, const VPoint& anchorPoint, const VPoint& previousPoint, const VPoint& nextPoint, Boolean mouseDidMove, Boolean turnItOn); // Override this if your Tracker calls back to the view (the Default) and you want // to display any tracking feedback virtual void TrackMouse(TrackPhase aTrackPhase, VPoint& anchorPoint, VPoint& previousPoint, VPoint& nextPoint, Boolean mouseDidMove); // Override this if your Tracker calls back to the view (the Default) an you want // to display any tracking feedback //------------------------------------------------------------------------------------ // View hierarchy management //------------------------------------------------------------------------------------ virtual void AddedASubView(TView* newSubView); // Called by AddSubView to notify this view that a subview was added. Calls // fSuperView->AddedASubView so that the notification is passed on to all // superviews virtual void RemovedASubView(TView* theSubView); // Called by RemoveSubView to notify this view that a subview was removed. Calls // fSuperView->RemovedASubView so that the notification is passed on to all // superviews virtual void BeInSuperView(TView* itsSuperView); // Called to notify this view that it has become a subview of theSuperView. // theSuperView can be NULL. Called by TView::AddSubView and TView::RemoveSubView virtual void SetHLPenState(HLState fromHL, HLState toHL); // Set the pen state for highlighting by XOR, given the highlight transition. You // can use this if you use Paint<X> or Frame<X> or line drawing for your // highlighting. //------------------------------------------------------------------------------------ // Drag and Drop Methods //------------------------------------------------------------------------------------ #if qDrag void HandleDragCursor(const VPoint& theMouse, RgnHandle cursorRegion); virtual Boolean DoSetDragCursor(const VPoint& localPoint, RgnHandle cursorRegion, RgnHandle& dragCursorRegion); // Can be overridden to set the drag cursor and compute a drag cursor region. // The default calls DoMakeDragCursorRegion and calls WillDrag, and sets the // cursor to the drag "open hand" if a mouse down would cause a drag. // dragCursorRegion should be NULL on entry, and must be disposed after calling. virtual short GetWillDragCursorID(); // Get the resource id of the cursor that indicates that the mouse is // over draggable content. virtual short GetIsDraggingCursorID(); // Get the resource id of the cursor that indicates that the user is dragging. virtual RgnHandle DoMakeDragCursorRegion(); // Create and return a region in local coordinates that can be used // to test whether the mouse is in a location that would initiate a // drag. This region is also used by DoSetCursor to create a cursor // sleep region virtual Boolean WillDrag(const VPoint& localMouse, const RgnHandle dragCursorRegion); // Returns true if the view wants to drag based on the mouse location virtual TView* DoGetDragProxy(); // Dragging view may provide a proxy to manage the drag operation. Not // necessary in most cases. void HandleDrag(TToolboxEvent* event); // Initiate a drag operation virtual void DoAddDragContent(); // Add drag items, flavors, and promises to the current drag operation virtual RgnHandle DoMakeDragOutlineRegion(); // Create and return a region in local coordinates that can be drawn // to represent data being dragged virtual Boolean WillAcceptDrop(CDragItemIterator& dragItemIterator); // Return true if the view will accept the drop. virtual void DoDragEnter(); // Become the drop target. Set up private data necessary for tracking // the drag within the view. virtual RgnHandle DoMakeDropHiliteRegion(); // Create and return a region in local coordinates that can be drawn // to represent that the view is droppable. virtual void DoDragWithin(const VPoint& localMouse); // update visual drag tracking indication based on the mouse coords. virtual void DoDragLeave(); // Clean up and remove any view-managed hiliting. virtual Boolean DoMakeDropLocationDescriptor(CAEDesc& dropLocationDesc); // return an AppleEvent descriptor describing the drop location. virtual Boolean WillDragMove(TView *destinationView); // If the drag initiated in this application, return true if data should // be moved instead of copied. virtual TCommand* DoMakeDragDropCommand(CommandNumber itsCommandNumber, CDragItemIterator& dragItemIterator); // Create a drag drop command that will be posted by the drag session. virtual void DoFulfillPromise(TDragItem* promisedItem); // Provide data for promised flavors // // If qDrag is false, these accessors will still be around but they won't do // anything. // inline Boolean GetDraggable() const { return fDraggable; } inline void SetDraggable(Boolean isDraggable) { fDraggable = isDraggable; } inline Boolean GetDroppable() const { return fDroppable; } void SetDroppable(Boolean isDroppable); inline short GetDragMoveDeterminer() const { return fDragMoveDeterminer; } inline void SetDragMoveDeterminer(short dragMoveDeterminer) { fDragMoveDeterminer = dragMoveDeterminer; } inline IDType GetDragMoveFamily() const { return fDragMoveFamily; } inline void SetDragMoveFamily(IDType dragMoveFamily) { fDragMoveFamily = dragMoveFamily; } #else inline Boolean GetDraggable() const { return FALSE; } inline void SetDraggable(Boolean /* isDraggable */) { } inline Boolean GetDroppable() const { return FALSE; } void SetDroppable(Boolean isDroppable); inline short GetDragMoveDeterminer() const { return kNeverMove; } inline void SetDragMoveDeterminer(short /* dragMoveDeterminer */) { } inline IDType GetDragMoveFamily() const { return kNoIdentifier; } inline void SetDragMoveFamily(IDType /* dragMoveFamily */) { } #endif // qDrag //---------------------------------------------------------------------------------------- // static functions //---------------------------------------------------------------------------------------- public: static void InitUView(Boolean initGX = TRUE); // Initialize the view system. // if initGX is TRUE then QuickDraw GX will be initialized static void TerminateUView(); // Terminate the view system static void GetFocus(FocusRec& theFocusRec); // gets the current focus into a focusrec. The theFocusRec.itsPortInfo.clipRgn must be // a valid rgn.Useful for saving and restoring the focus behind MacApp's back. static void SetFocus(const FocusRec& theFocusRec); // sets the current focus from a focus rec static void GetViewPortInfo(ViewPortInfo& theViewPortInfo); // gets the current PortInfo into a ViewPortInfo. theViewPortInfo.clipRgn must be a // valid rgn. static void SetViewPortInfo(const ViewPortInfo& theViewPortInfo); // sets the current PortInfo from a ViewPortInfo static Boolean IsRectVisible(const CRect& r); // Determine if a CRect is visible in the current grafport. static Boolean IsRectDrawable(const CRect& r); // Determine if any portion of a CRect intersects the ports visRgn AND clipRgn. static void VisibleRect(CRect& rectToRestrict); // trims the supplied CRect down to its intersection with the port's visRgn static void DrawableRect(CRect& rectToRestrict); // trims the supplied CRect down to its intersection with the port's visRgn AND // clipRgn. static void VisibleRgn(RgnHandle rgn); // trims the supplied rgn down to its intersection with the port's visRgn static void DrawableRgn(RgnHandle rgn); // trims the supplied rgn down to its intersection with the port's visRgn AND // clipRgn. static Boolean IsPtVisible(CPoint pt); // Determine if a pt intersects the ports visRgn static Boolean IsPtDrawable(CPoint pt); // Determine if a pt intersects the ports visRgn AND clipRgn. static void PtAndRgn(CPoint aPoint, RgnHandle aRegion); // Adds the given CPoint to the given region static void VRectAndRgn(const VRect& theVRect, RgnHandle theRgn); // Call this procedure to add theVRect to theRgn. #if qDebug static void WriteFocus(); // Writes information about the current focus to the output #endif static RgnHandle GetClipRegion(GrafPtr theGrafPtr); // Return the clipRgn //---------------------------------------------------------------------------------------- // data members //---------------------------------------------------------------------------------------- public: VPoint fLocation; // the location in superview coordinates VPoint fSize; // the size of this view VPoint fTranslation; // translation of coordinates required to // account for the origin of the view's // local coordinate system. VPoint fViewToQDOffset; // the computed translation of coordinates // necessary to account for adjustment of // large views down to QD space. // Access only through GetViewToQDOffset! VRect fVisibleExtent; // The extent of the view that could be // "visible" through all its superviews // (not taking clipping into account // Access only through GetVisibleExtent! CPoint fQDOrigin; // the computed QD origin for the port to // account for the view's location. // Access only through GetQDOrigin! TView* fSuperView; // the current superview TView* fSubView; // first of subviews of this view (linked list) TView* fNextView; // first of siblings of this view (linked list) TDocument* fDocument; // the associated document if any. TDrawingEnvironment* fDrawingEnvironment; // PenSize etc. TAdornerList* fAdorners; // The list of adorners long fUserArea; // assigned from view template for use // by client short fTemplateVersion; // version number of the template used to // instantiate this view short fHelpIndex; ResNumber fHelpID; ResNumber fCursorID; SizeDeterminer fSizeDeterminer[2]; // how this view's size is to be // determined HLState fActiveHL; // the current highlighting state for this // view in an active window. Typically hlOn. HLState fInactiveHL; // the current highlighting state for this // view in an inactive window. Typically // hlOff or hlDim Boolean fHandlesCursor; // true if the view tracks the mouse for // cursor setting Boolean fLetsSubViewsHandleCursor; // true if subviews should be given a // chance to set the cursor Boolean fHandlesHelp; // true if the view tracks the mouse for // showing help balloons Boolean fHandlesFirstClicks; // true if the view handles first clicks Boolean fLetsSubViewsHandleHelp; // true if subviews should be given a // chance to display help Boolean fShown; // is this view to be shown Boolean fWantsToBeTarget; // If true, then clicking in this view or tabbing // makes it the target. Boolean fCoordinatesAreInvalid; // Set true by InvalidateCoordinates // Set false by UpdateCoordinates #if qDrag protected: Boolean fDraggable; // can the view be dragged Boolean fDroppable; // can the view receive drops short fDragMoveDeterminer; // defines context for drag move IDType fDragMoveFamily; // defines dragmove family within specified context #endif //---------------------------------------------------------------------------------------- // static data members //---------------------------------------------------------------------------------------- public: static TView* gFocusedView; // the view that is currently focused static Boolean gPrinting; // True if currently Printing static Boolean gDrawingPictScrap; // True if a view's Draw routine is being called in order to create PICT data in the // Desk Scrap; your View.Draw can check this routine, and insert PictComments as // appropriate if it wishes to have them in the Picture in the Desk Scrap static TView* gDrawingPictScrapView; // the view being currently drawn in the PICT scrap ??? this stuff is a good candidate // for a small change to the view architecture to more easily allow providing // alternate drawing environments #if qGXViews || qGXPrinting static gxGraphicsClient gGXGraphicsClient; // The main GX Graphic client (when used). #endif }; //---------------------------------------------------------------------------------------- // CSubViewIterator: A simple iterator for subviews. //---------------------------------------------------------------------------------------- class CSubViewIterator { public: CSubViewIterator(const TView* theSuperView, Boolean itsForward = TRUE); inline Boolean More() const { return fCurrentSubView != NULL; } // Returns true if there are more elements to iterate over void Reset(); // override // Resets the iterator to begin again inline TView* CurrentSubView() const { return fCurrentSubView; } // returns the current View TView* FirstSubView(); // Resets the iterator to begin again and returns the first subview in the subview list TView* NextSubView(); // increments and then returns the subview in the subview list protected: void Advance(); // Advances the iteration inline TView* NextView(TView* aView) const { return aView->fNextView; } // returns the next subview in the subview list TView* PreviousView(TView* aView) const; // returns the previous subview in the subview list inline TView* FirstView() const { return (TView *)fFirstView; } // returns the first subview in the subview list TView* LastView() const; // returns the last subview in the subview list private: const TView* fFirstView; TView* fCurrentSubView; protected: Boolean fIterateForward; }; //---------------------------------------------------------------------------------------- // TIncludeView: specialized view which includes another view resource. //---------------------------------------------------------------------------------------- class TIncludeView : public TView { MA_DECLARE_CLASS; public: //------------------------------------------------------------------------------------ // Creation/ Destruction Methods //------------------------------------------------------------------------------------ TIncludeView(); // Constructor virtual ~TIncludeView(); // Destructor void IIncludeView(TDocument* itsDocument, TView* itsSuperView, short includeRsrcID, const VPoint& itsSubViewOffset, const CStr255& resourceName, short resourceAttributes); //------------------------------------------------------------------------------------ // Standard signature support. //------------------------------------------------------------------------------------ virtual IDType GetStandardSignature(); // override // Returns this class's standard signature. //------------------------------------------------------------------------------------ // Stream I/O protocol support. //------------------------------------------------------------------------------------ virtual void DoPostCreate(TDocument* itsDocument); virtual void ReadFields(TStream* aStream); virtual void WriteFields(TStream* aStream); virtual void WriteSubViews(TStream* aStream); // don't write any subviews //------------------------------------------------------------------------------------ // Frame (Location and Size) Methods //------------------------------------------------------------------------------------ virtual void SubViewChangedFrame(TView* theSubView, const VRect& oldFrame, const VRect& newFrame, Boolean invalidate); // Called when one of our subviews changes frame. //---------------------------------------------------------------------------------------- // data members //---------------------------------------------------------------------------------------- public: CStr255 fResourceName; VPoint fItsSubViewOffset; // offset of view in superview short fIncludeRsrcID; // the included view's rsrc id short fResourceAttributes; }; #endif